home *** CD-ROM | disk | FTP | other *** search
/ Hottest 6 / Hottest 6 (1996)(PDSoft)[!].iso / software / fredfish / 1072.lha / Programs / RexxDosSupport / rexxdossupport.doc < prev    next >
Text File  |  1995-04-10  |  21KB  |  627 lines
  1. TABLE OF CONTENTS
  2.  
  3. rexxdossupport.library/--Disclaimer--
  4. rexxdossupport.library/--background--
  5. rexxdossupport.library/--history--
  6. rexxdossupport.library/--installation--
  7. rexxdossupport.library/Delete
  8. rexxdossupport.library/DeleteVar
  9. rexxdossupport.library/Fault
  10. rexxdossupport.library/GetVar
  11. rexxdossupport.library/MakeDir
  12. rexxdossupport.library/MatchPattern
  13. rexxdossupport.library/ParsePattern
  14. rexxdossupport.library/ReadArgs
  15. rexxdossupport.library/Rename
  16. rexxdossupport.library/SetComment
  17. rexxdossupport.library/SetProtection
  18. rexxdossupport.library/SetVar
  19. rexxdossupport.library/--Disclaimer--   rexxdossupport.library/--Disclaimer--
  20.  
  21. Disclaimer
  22. ----------
  23.  
  24.    Permission is granted to make and distribute verbatim copies  of  this
  25. manual provided the copyright  notice  and  this  permission  notice  are
  26. preserved on all copies.
  27.  
  28. COPYRIGHT
  29.  
  30.    Copyright (C) 1994 by hartmut Goebel
  31.  
  32.    No program, document, data file or  source  code  from  this  software
  33. package, neither in whole nor in part, may be included or used  in  other
  34. software packages unless it is authorized by a  written  permission  from
  35. the author.
  36.  
  37.  
  38. NO WARRANTY
  39.  
  40.    There is no warranty for this software package.  Although  the  author
  41. has tried to prevent errors, he can't guarantee that the software package
  42. described in this document is 100% reliable. You are therefore using this
  43. material at your own risk. The author cannot be made responsible for  any
  44. damage which is caused by using this software package.
  45.  
  46.  
  47. DISTRIBUTION
  48.  
  49.    This software package is freely distributable. It may be  put  on  any
  50. media which is used for the distribution of free  software,  like  Public
  51. Domain disk collections, CDROMs, FTP servers or bulletin board systems.
  52.  
  53.    In  order  to  ensure  the  integrity  of   this   software   package,
  54. distributors should use the original archive file  rexxdossupport2_2.lha.
  55. The author cannot be  made  responsible  if  this software  package   has
  56. become unusable due to modifications of  the  archive  contents   or   of
  57. the archive file itself.
  58.  
  59.    There is no limit on the costs  of  the  distribution,  e.g.  for  the
  60. media, like floppy disks, streamer tapes or compact disks, or the process
  61. of duplicating. Such limits have been proven to be harmful to the idea of
  62. freely distributable software, e.g. instead of reducing the price of  the
  63. floppy disk below the limit, the software was  simply  removed  from  the
  64. master disk.
  65.  
  66.    Although the author does not impose any limit on the  distribution  of
  67. this software package, he would like to express his personal opinions  on
  68. this matter:
  69.  
  70.    * This software package should be made available to everyone  free  of
  71.      charge whenever it is possible.
  72.  
  73.    * If you have acquired this software package under  normal  conditions
  74.      from a Public Domain dealer on a floppy disk at a price higher  than
  75.      5DM or US $5, then you have definitely paid too much.  Please  don't
  76.      support this improper profit making  any  longer  and  switch  to  a
  77.      cheaper source as soon as possible.
  78.  
  79.  
  80. USAGE RESTRICTIONS
  81.  
  82.    No program, document, data file or  source  code  from  this  software
  83. package, neither in whole nor in part, may be used on any  machine  which
  84. is used
  85.  
  86.    * for the research, development, construction, testing  or  production
  87.      of weapons or other military applications. This  also  includes  any
  88.      machine which is  used  in  the  education  for  any  of  the  above
  89.      mentioned purposes.
  90.  
  91.    * by people who accept, support or use violence against other  people,
  92.      e.g. citizens from foreign countries.
  93.  
  94. rexxdossupport.library/--background--   rexxdossupport.library/--background--
  95.  
  96.                 rexxdossupport.library 2.2
  97.                 ==========================
  98.  
  99.             Copyright (C) 1994 by hartmut Goebel
  100.  
  101.  
  102.    After programming ARexx script for quite a while, I missed some
  103.    function found in dos.library --  especially access to
  104.    environment variables and the comfortable argument parsing. Since
  105.    there seamed to be no ARexx function library which implements
  106.    this functions, I decited to write my own. And here it is.
  107.  
  108.    This are the functions handled by this library.
  109.    · ReadArgs()
  110.    · GetVar(), SetVar(), DeleteVar()
  111.    · ParsePattern(), MatchPattern() - even case-insensitive
  112.    · Fault()
  113.  
  114.    new functions for version 2.1
  115.    · Delete(), Rename(), MakeDir()
  116.    · SetComment(), SetProtection()
  117.  
  118.    Enjoy it!
  119.    +++hartmut
  120.  
  121. rexxdossupport.library/--history--         rexxdossupport.library/--history--
  122.  
  123.   2.3  01 Apr 1995
  124.        · fixed problem with synonyms: foo=bar lead to illegal
  125.          variable named 'FOO=BAR'. Now allways th first synonym is
  126.          taken as var-name.
  127.  
  128.   2.2  18 Jul 1994
  129.        · Shame on me! library names must be lowercase
  130.        · Some more notes in documentation
  131.   2.1  03 Jun 1994
  132.        · removed curious bug in ReadArgs() (uninitialized var,
  133.          introduced in V2.0)
  134.   2.0  07 May 1994 (never released)
  135.        · stronger check for present args to avoid NIL-Traps
  136.        · new functions: Delete(), Rename(), MakeDir(),
  137.                         SetComment(), SetProtection()
  138.   1.4  01 Feb 1994
  139.        · only significant part of parsed pattern is copied
  140.          into the ARexx Argstring
  141.   1.3  23 Jan 1994
  142.        · uses module RxLibsSupport [hG]
  143.   1.2  18 Jan 1994
  144.        · finished dokumentation
  145.        · UnsetVar() - like shell commnad - renamed to
  146.          DeleteVar() - like in dos.library
  147.        · SetVar() no longer accepts option "Binary"
  148.   1.1  16 Jan 1994
  149.        initial release
  150.  
  151. rexxdossupport.library/--installation--rexxdossupport.library/--installation--
  152.  
  153.    To use rexxdossupport.library, just copy is to yout LIBS:
  154.    directory. That's all.
  155.  
  156.    The LVO for the ARexx-Dispatcher is -30.
  157.        NB: it's the only LVO for this library :-)
  158.  
  159.    So, in every ARexx-Script you want to use rexxdossupport.library,
  160.    insert
  161.  
  162.       call addlib("rexxdossupport.library",0,-30,2)
  163.  
  164.    somewhere before the first call to one of the routines
  165.    implemented in this library.
  166.    Since ARexx does not check whether the lib can be opened but only
  167.    inserts the name into a list, the result value from addlib() can
  168.    be ignored in most cases. The value would be interesting to check
  169.    if the added note will require the same library version, but I
  170.    don't know how to find this out.
  171.  
  172. rexxdossupport.library/Delete                   rexxdossupport.library/Delete
  173.  
  174.    NAME
  175.        Delete -- Delete a file or directory (V2)
  176.  
  177.    SYNOPSIS
  178.        success = Delete( name )
  179.  
  180.    FUNCTION
  181.        This attempts to delete the file or directory specified by
  182.        'name'. If the deletion fails an error is returned and the
  183.        rexx variable RC is set. Note that all the files within a
  184.        directory must be deleted before the directory itself can be
  185.        deleted.
  186.  
  187.    INPUTS
  188.        name     - name of file or directory to delete.
  189.  
  190.    RESULT
  191.        success - If TRUE, the file was sucessfully deleted,
  192.                  FALSE indicates failure.
  193.  
  194.        RC (rexx variable) - contains the dos error code if the
  195.                function was not successfull. This can can directly
  196.                be used as input for Fault().
  197.  
  198.    SEE ALSO
  199.        Fault(), dos.library/DeleteFile()
  200.  
  201. rexxdossupport.library/DeleteVar             rexxdossupport.library/DeleteVar
  202.  
  203.    NAME
  204.        DeleteVar -- Deletes a local or environment variable
  205.  
  206.    SYNOPSIS
  207.        success = DeleteVar( name, [ "Local" | "Global" ] )
  208.  
  209.    FUNCTION
  210.        Deletes a local or environment variable.
  211.  
  212.    INPUTS
  213.        name     - variable name.  Note variable names follow
  214.                   filesystem syntax and semantics.
  215.        "Global" - tries to get a global env variable.
  216.        "Local"  - tries to get a local variable (see note below).
  217.  
  218.                 The default is to delete a local variable if found, otherwise
  219.                 a global environment variable if found.
  220.  
  221.    RESULT
  222.        success - If TRUE, the variable was sucessfully deleted,
  223.                  FALSE indicates failure.
  224.  
  225.    NOTES
  226.       Since ARexx spawn a new process of each script -- even if
  227.       started from Shell -- option "Local" may not work as supposed.
  228.  
  229.    SEE ALSO
  230.        GetVar(), SetVar(), dos.library/DeleteVar()
  231.  
  232. rexxdossupport.library/Fault                     rexxdossupport.library/Fault
  233.  
  234.    NAME
  235.        Fault -- Returns the text associated with a DOS error code
  236.  
  237.    SYNOPSIS
  238.        string = Fault( code, header )
  239.  
  240.    FUNCTION
  241.        This routine obtains the error message text for the given
  242.        error code. The header is prepended to the text of the error
  243.        message, followed by a colon. By convention, error messages
  244.        should be no longer than 80 characters, and preferably no
  245.        more than 60.
  246.  
  247.        The value returned by IoErr() (not available in this library)
  248.        is set to the code passed in. If there is no message for the
  249.        error code, the message will be "Error code <number>\n".
  250.  
  251.        The string will be empty if the code passed in was 0.
  252.  
  253.    INPUTS
  254.        code   - Error code
  255.        header - header to output before error text
  256.  
  257.    RESULT
  258.        string - error massage as described above.
  259.  
  260.        RC (rexx variable) - 5 when error message is empty
  261.                             0 otherwise
  262.  
  263.    BUGS
  264.       I've been told that this function returns only an empty sting.
  265.       Since nobody gave me further information, I can't fix it.
  266.  
  267.    SEE ALSO
  268.        dos.library/Fault(), dos.library/IoErr()
  269.  
  270. rexxdossupport.library/GetVar                   rexxdossupport.library/GetVar
  271.  
  272.    NAME
  273.        GetVar -- Returns the value of a local or global variable
  274.  
  275.    SYNOPSIS
  276.        string = GetVar( name, ["Local" | "Global"], ["Binary"] )
  277.  
  278.    FUNCTION
  279.        Gets the value of a local or environment variable.  It is advised to
  280.        only use ASCII strings inside variables, but not required.  This stops
  281.        putting characters into the destination when a \n is hit, unless
  282.        "Binary" is specified.  (The \n is not stored in the buffer.)
  283.  
  284.    INPUTS
  285.        name     - variable name.
  286.        "Global" - tries to get a global env variable.
  287.        "Local"  - tries to get a local variable (see note below).
  288.        "Binary" - don't stop at \n
  289.                   in this mode the string returned is not null terminated
  290.  
  291.                 The default is to try to get a local variable first,
  292.                 then to try to get a global environment variable.
  293.  
  294.    RESULT
  295.        string - contents of the variable
  296.  
  297.        RC (rexx variable) - 5 when variable does not exist,
  298.                             0 otherwise
  299.  
  300.    EXAMPLE
  301.        /* */
  302.        username = GetVar("username")
  303.        if RC = 5 then
  304.          say "Variable 'username' is not set"
  305.        else
  306.          say "Variable 'username' is" username
  307.  
  308.    NOTES
  309.       contents may be max. 512 char.
  310.  
  311.       Since ARexx spawn a new process of each script -- even if
  312.       started from Shell -- option "Local" may not work as supposed.
  313.  
  314.    BUGS
  315.        Due to a bug in dos.library, binary global vars will be null
  316.        terminated in V37, V38.
  317.  
  318.    SEE ALSO
  319.      SetVar(), DeleteVar(), dos.library/GetVar()
  320.  
  321. rexxdossupport.library/MakeDir                 rexxdossupport.library/MakeDir
  322.  
  323.    NAME
  324.        MakeDir -- Create a new directory (V2)
  325.  
  326.    SYNOPSIS
  327.        success = MakeDir( name )
  328.  
  329.    FUNCTION
  330.        MakeDir creates a new directory with the specified name. If
  331.        it fails an error is returned and the rexx variable RC is
  332.        set.  Directories can only be created on devices which
  333.        support them, e.g. disks.
  334.  
  335.    INPUTS
  336.        name     - name of directory to create
  337.  
  338.    RESULT
  339.        success - If TRUE, the variable was sucessfully deleted,
  340.                  FALSE indicates failure.
  341.  
  342.        RC (rexx variable) - contains the dos error code if the
  343.                function was not successfull. This can can directly
  344.                be used as input for Fault().
  345.  
  346.    SEE ALSO
  347.        Fault(), dos.library/CreateDir()
  348.  
  349. rexxdossupport.library/MatchPattern       rexxdossupport.library/MatchPattern
  350.  
  351.    NAME
  352.        MatchPattern --  Checks for a pattern match with a string
  353.  
  354.    SYNOPSIS
  355.        match = MatchPattern(pattern, string, ["Nocase"], ["Parsed"] )
  356.  
  357.    FUNCTION
  358.        Checks for a pattern match with a string.
  359.        This routine is case-sensitive by default. Use option
  360.        "NoCase" for case-insensitve matching.
  361.  
  362.        Use option "Parsed" to indicate that pattern has already been
  363.        tokenized using ParsePattern(). Make sure to use or use not
  364.        "NoCase" for both function.
  365.  
  366.    INPUTS
  367.        pattern  - pattern string to match
  368.        string   - string to match against given pattern
  369.        "Nocase" - match should be case-insensitve
  370.        "Parsed" - pattern has already been parsed using ParsePattern()
  371.  
  372.    RESULT
  373.        match - success or failure of pattern match.
  374.  
  375.    SEE ALSO
  376.        ParsePattern(), dos.library/MatchPattern(),
  377.        dos.library/MatchPatternNoCase()
  378.  
  379. rexxdossupport.library/ParsePattern       rexxdossupport.library/ParsePattern
  380.  
  381.    NAME
  382.        ParsePattern -- Create a tokenized string for MatchPattern()
  383.  
  384.    SYNOPSIS
  385.        token = ParsePattern( pattern, ["NoCase"] )
  386.  
  387.    FUNCTION
  388.        Tokenizes a pattern, for use by MatchPattern().  Also indicates
  389.        if there are any wildcards in the pattern (i.e. whether it might match
  390.        more than one item).
  391.  
  392.        For a description of the wildcards, see dos.library/ParsePattern().
  393.  
  394.    INPUTS
  395.        pattern  - unparsed wildcard string to search for.
  396.  
  397.    RESULT
  398.        token    - output string, tokenized version of input.
  399.  
  400.        RC (rexx variable) - 5 when does not contain wildcards
  401.                             0 otherwise
  402.  
  403.    BUGS
  404.        Since is't not clear wether the resulting token may contain
  405.        null charakters, the returned string is always
  406.        2 * Length(pattern) + 2 bytes long.
  407.  
  408.    SEE ALSO
  409.        ParsePattern(), dos.library/ParsePattern(),
  410.        dos.library/ParsePatternNoCase()
  411.  
  412. rexxdossupport.library/ReadArgs               rexxdossupport.library/ReadArgs
  413.  
  414.    NAME
  415.        ReadArgs -- Parse argument string using Dos/ReadArgs()
  416.  
  417.    SYNOPSIS
  418.        okay = ReadArgs( arguments, template, [stem] )
  419.  
  420.    FUNCTION
  421.        Parses an argument string according to a template. See
  422.        dos.library/ReadArgs() for details and describtion of the
  423.        template.
  424.  
  425.        This function supports the following template options:
  426.  
  427.        /S - Switch.  Resulting variable will be either true (1) or
  428.             false (0).
  429.        /N - Number.
  430.        /M - Multiple strings.  See below for further information.
  431.  
  432.        /K - Keyword.      }
  433.        /A - Required.     }  handled by dos
  434.        /F - Rest of line. }
  435.  
  436.        /T (toggle) is not supported, since handling this would be a
  437.        large turnover with small profit.
  438.  
  439.    INPUTS
  440.        arguments - the string to be parsed
  441.        template  - dos.library/ReadArgs()-style like template
  442.        stem      - stem prefix for resulting variables (optional)
  443.  
  444.    RESULT
  445.        okay  - boolean value indicating success.
  446.  
  447.        RC (rexx variable) - contains the dos error code if the
  448.                function was not successfull. This can can directly
  449.                be used as input for Fault().
  450.  
  451.        For each item in the template which has a corresponding
  452.        argument, a Rexx variable will be created. The variable's
  453.        name is the item's name prefixed by the stem name (if given).
  454.  
  455.        Items with option /M will result in a stem variable with a
  456.        .COUNT node containing the number of elements. If no fitting
  457.        arguments is passed, .COUNT will be zero.
  458.        The entries will be in stem nodes .0 to .n (where n is
  459.        .COUNT-1).
  460.  
  461.    EXAMPLE
  462.        /* ReadArgsExample.rexx */
  463.        /* AddLib() here */
  464.  
  465.        parse arg args /* get the arguments w/o ARexx-Parsing */
  466.  
  467.        template = "Files/M,Method/K,MinSize/K/N,Test/S"
  468.  
  469.        /* set defaults */
  470.        Method = "NUKE"; MinSize = 512;
  471.  
  472.        /* no stem given: results are assigned to simple variables */
  473.  
  474.        if ReadArgs(args,template) then
  475.          say 'Method =' method '  MinSize =' MinSize '  Test =' test
  476.          do i = 0 by 1 for file.count
  477.            say name.1
  478.          end
  479.  
  480.        /* stem given: results are assigned to stem variable */
  481.        /* since the default values are set as non-stem variables,
  482.         * they are not overwritten by the following call even if
  483.         * given
  484.         */
  485.  
  486.        if ReadArgs(input,template,"args.") then
  487.          say 'Method =' args.method '  MinSize =' args.MinSize ' Test =' args.test
  488.          do i = 0 by 1 for args.file.count
  489.            say args.name.1
  490.          end
  491.  
  492.    SEE ALSO
  493.       Fault(), dos.library/ReadArgs()
  494.  
  495. rexxdossupport.library/Rename                   rexxdossupport.library/Rename
  496.  
  497.    NAME
  498.        Rename -- Rename a directory or file (V2)
  499.  
  500.    SYNOPSIS
  501.        success = Rename( oldName, newName )
  502.  
  503.    FUNCTION
  504.        Rename() attempts to rename the file or directory specified
  505.        as 'oldName' with the name 'newName'. If the file or
  506.        directory 'newName' exists, Rename() fails and returns an
  507.        error. Both 'oldName' and the 'newName' can contain a
  508.        directory specification. In this case, the file will be moved
  509.        from one directory to another.
  510.  
  511.        Note: it is impossible to Rename() a file from one volume to
  512.        another.
  513.  
  514.    INPUTS
  515.        oldName - pointer to a null-terminated string
  516.        newName - pointer to a null-terminated string
  517.  
  518.    RESULT
  519.        success - If TRUE, the variable was sucessfully deleted,
  520.                  FALSE indicates failure.
  521.  
  522.        RC (rexx variable) - contains the dos error code if the
  523.                function was not successfull. This can can directly
  524.                be used as input for Fault().
  525.  
  526.    SEE ALSO
  527.        Fault(), dos.library/Rename()
  528.  
  529. rexxdossupport.library/SetComment           rexxdossupport.library/SetComment
  530.  
  531.    NAME
  532.        SetComment -- Change a files' comment string (V2)
  533.  
  534.    SYNOPSIS
  535.        success = SetComment( name, comment )
  536.  
  537.    FUNCTION
  538.        SetComment() sets a comment on a file or directory. The
  539.        comment may be up to 80 characters in the current ROM
  540.        filesystem (and RAM:).  Note that not all filesystems will
  541.        support comments (for example, NFS usually will not), or the
  542.        size of comment supported may vary.
  543.  
  544.    INPUTS
  545.        name     - name of file or directory to set comment
  546.        comment  - comment to be set
  547.  
  548.    RESULT
  549.        success - If TRUE, the variable was sucessfully deleted,
  550.                  FALSE indicates failure.
  551.  
  552.        RC (rexx variable) - contains the dos error code if the
  553.                function was not successfull. This can can directly
  554.                be used as input for Fault().
  555.  
  556.    SEE ALSO
  557.        SetProtection(), Fault(), dos.library/SetComment()
  558.  
  559. rexxdossupport.library/SetProtection     rexxdossupport.library/SetProtection
  560.  
  561.    NAME
  562.        SetProtection -- Set protection for a file or directory (V2)
  563.  
  564.    SYNOPSIS
  565.        success = SetProtection( name, mask )
  566.  
  567.    FUNCTION
  568.        SetProtection() sets the protection attributes on a file or
  569.        directory.  See <dos/dos.h> for a listing of protection bits.
  570.  
  571.        The archive bit should be cleared by the filesystem whenever
  572.        the file is changed.  Backup utilities will generally set the
  573.        bit after backing up each file.
  574.  
  575.        The V36 Shell looks at the execute bit, and will refuse to
  576.        execute a file if it is set.
  577.  
  578.        Other bits will be defined in the <dos/dos.h>include files.
  579.        Rather than referring to bits by number you should use the
  580.        definitions in <dos/dos.h>.
  581.  
  582.    INPUTS
  583.        name     - name of file or directory to set protection
  584.        mask     - the protection mask required
  585.  
  586.    RESULT
  587.        success - If TRUE, the variable was sucessfully deleted,
  588.                  FALSE indicates failure.
  589.  
  590.        RC (rexx variable) - contains the dos error code if the
  591.                function was not successfull. This can can directly
  592.                be used as input for Fault().
  593.  
  594.    SEE ALSO
  595.        SetComment(), Fault(), dos.library/SetProtection()
  596.  
  597. rexxdossupport.library/SetVar                   rexxdossupport.library/SetVar
  598.  
  599.    NAME
  600.        SetVar -- Sets a local or environment variable
  601.  
  602.    SYNOPSIS@{ub}
  603.        success = SetVar( name, ["Local" | "Global"] )
  604.  
  605.    FUNCTION
  606.        Sets a local or environment variable.  It is advised to only use
  607.        ASCII strings inside variables, but not required.
  608.  
  609.    INPUTS
  610.        name     - variable name.
  611.        "Global" - tries to get a global env variable.
  612.        "Local"  - tries to get a local variable (see note below).
  613.  
  614.                The default is to set a local environment variable.
  615.  
  616.    RESULT
  617.        success - If non-zero, the variable was sucessfully set, FALSE
  618.                  indicates failure.
  619.  
  620.    NOTES
  621.       Since ARexx spawn a new process of each script -- even if
  622.       started from Shell -- option "Local" may not work as supposed.
  623.  
  624.    SEE ALSO
  625.      GetVar(), DeleteVar(), dos.library/SetVar()
  626.  
  627.